@j0hanz/superfetch 2.1.0 → 2.1.2

package/README.md

@@ -444,16 +444,17 @@ Set environment variables in your MCP client `env` or in the shell before starti
 
 ### Core Server Settings
 
-| Variable        | Default              | Description                                                                       |
-| --------------- | -------------------- | --------------------------------------------------------------------------------- |
-| `HOST`          | `127.0.0.1`          | HTTP bind address                                                                 |
-| `PORT`          | `3000`               | HTTP server port (1024-65535)                                                     |
-| `USER_AGENT`    | `superFetch-MCP/2.0` | User-Agent header for outgoing requests                                           |
-| `CACHE_ENABLED` | `true`               | Enable response caching                                                           |
-| `CACHE_TTL`     | `3600`               | Cache TTL in seconds (60-86400)                                                   |
-| `LOG_LEVEL`     | `info`               | Logging level. Only `debug` enables verbose logs; other values behave like `info` |
-| `ALLOW_REMOTE`  | `false`              | Allow binding to non-loopback hosts (OAuth required)                              |
-| `ALLOWED_HOSTS` | (empty)              | Additional allowed Host/Origin values (comma/space separated)                     |
+| Variable               | Default              | Description                                                                       |
+| ---------------------- | -------------------- | --------------------------------------------------------------------------------- |
+| `HOST`                 | `127.0.0.1`          | HTTP bind address                                                                 |
+| `PORT`                 | `3000`               | HTTP server port (1024-65535)                                                     |
+| `USER_AGENT`           | `superFetch-MCP/2.0` | User-Agent header for outgoing requests                                           |
+| `CACHE_ENABLED`        | `true`               | Enable response caching                                                           |
+| `CACHE_TTL`            | `3600`               | Cache TTL in seconds (60-86400)                                                   |
+| `LOG_LEVEL`            | `info`               | Logging level. Only `debug` enables verbose logs; other values behave like `info` |
+| `ALLOW_REMOTE`         | `false`              | Allow binding to non-loopback hosts (OAuth required)                              |
+| `ALLOWED_HOSTS`        | (empty)              | Additional allowed Host/Origin values (comma/space separated)                     |
+| `TRANSFORM_TIMEOUT_MS` | `30000`              | Worker transform timeout in milliseconds (5000-120000)                            |
 
 For HTTP server tuning (`SERVER_HEADERS_TIMEOUT_MS`, `SERVER_REQUEST_TIMEOUT_MS`, `SERVER_KEEP_ALIVE_TIMEOUT_MS`, `SERVER_SHUTDOWN_CLOSE_IDLE`, `SERVER_SHUTDOWN_CLOSE_ALL`), see `CONFIGURATION.md`.
 

package/dist/cache.js

@@ -5,9 +5,7 @@ import { config } from './config.js';
 import { sha256Hex } from './crypto.js';
 import { getErrorMessage } from './errors.js';
 import { logDebug, logWarn } from './observability.js';
-function isRecord(value) {
-    return typeof value === 'object' && value !== null;
-}
+import { isRecord } from './utils.js';
 export function parseCachedPayload(raw) {
     try {
         const parsed = JSON.parse(raw);
@@ -47,21 +45,121 @@ const CACHE_HASH = {
     URL_HASH_LENGTH: 16,
     VARY_HASH_LENGTH: 12,
 };
-function stableStringify(value) {
-    if (!isRecord(value)) {
-        if (value === null || value === undefined) {
-            return '';
+const CACHE_VARY_LIMITS = {
+    MAX_STRING_LENGTH: 4096,
+    MAX_KEYS: 64,
+    MAX_ARRAY_LENGTH: 64,
+    MAX_DEPTH: 6,
+    MAX_NODES: 512,
+};
+function bumpStableStringifyNodeCount(state) {
+    state.nodes += 1;
+    return state.nodes <= CACHE_VARY_LIMITS.MAX_NODES;
+}
+function stableStringifyPrimitive(value) {
+    if (value === null || value === undefined) {
+        return '';
+    }
+    const json = JSON.stringify(value);
+    return typeof json === 'string' ? json : '';
+}
+function stableStringifyArray(value, state) {
+    if (value.length > CACHE_VARY_LIMITS.MAX_ARRAY_LENGTH) {
+        return null;
+    }
+    const parts = ['['];
+    let length = 1;
+    for (let index = 0; index < value.length; index += 1) {
+        if (index > 0) {
+            parts.push(',');
+            length += 1;
+            if (length > CACHE_VARY_LIMITS.MAX_STRING_LENGTH)
+                return null;
+        }
+        const entry = stableStringifyInner(value[index], state);
+        if (entry === null)
+            return null;
+        parts.push(entry);
+        length += entry.length;
+        if (length > CACHE_VARY_LIMITS.MAX_STRING_LENGTH)
+            return null;
+    }
+    parts.push(']');
+    length += 1;
+    return length > CACHE_VARY_LIMITS.MAX_STRING_LENGTH ? null : parts.join('');
+}
+function stableStringifyRecord(value, state) {
+    const keys = Object.keys(value);
+    if (keys.length > CACHE_VARY_LIMITS.MAX_KEYS) {
+        return null;
+    }
+    keys.sort((a, b) => a.localeCompare(b));
+    const parts = ['{'];
+    let length = 1;
+    let isFirst = true;
+    for (const key of keys) {
+        const entryValue = value[key];
+        if (entryValue === undefined)
+            continue;
+        const encodedValue = stableStringifyInner(entryValue, state);
+        if (encodedValue === null)
+            return null;
+        const entry = `${JSON.stringify(key)}:${encodedValue}`;
+        if (!isFirst) {
+            parts.push(',');
+            length += 1;
+            if (length > CACHE_VARY_LIMITS.MAX_STRING_LENGTH)
+                return null;
+        }
+        parts.push(entry);
+        length += entry.length;
+        if (length > CACHE_VARY_LIMITS.MAX_STRING_LENGTH)
+            return null;
+        isFirst = false;
+    }
+    parts.push('}');
+    length += 1;
+    return length > CACHE_VARY_LIMITS.MAX_STRING_LENGTH ? null : parts.join('');
+}
+function stableStringifyObject(value, state) {
+    if (state.stack.has(value)) {
+        return null;
+    }
+    if (state.depth >= CACHE_VARY_LIMITS.MAX_DEPTH) {
+        return null;
+    }
+    state.stack.add(value);
+    state.depth += 1;
+    try {
+        if (Array.isArray(value)) {
+            return stableStringifyArray(value, state);
         }
-        return JSON.stringify(value);
+        return isRecord(value) ? stableStringifyRecord(value, state) : null;
     }
-    if (Array.isArray(value)) {
-        return `[${value.map((item) => stableStringify(item)).join(',')}]`;
+    finally {
+        state.depth -= 1;
+        state.stack.delete(value);
     }
-    const entries = Object.entries(value)
-        .filter(([, entryValue]) => entryValue !== undefined)
-        .sort(([a], [b]) => a.localeCompare(b))
-        .map(([key, entryValue]) => `${JSON.stringify(key)}:${stableStringify(entryValue)}`);
-    return `{${entries.join(',')}}`;
+}
+function stableStringifyInner(value, state) {
+    if (!bumpStableStringifyNodeCount(state)) {
+        return null;
+    }
+    if (value === null || value === undefined) {
+        return '';
+    }
+    if (typeof value !== 'object') {
+        return stableStringifyPrimitive(value);
+    }
+    return stableStringifyObject(value, state);
+}
+function stableStringify(value) {
+    const state = {
+        depth: 0,
+        nodes: 0,
+        stack: new WeakSet(),
+    };
+    return stableStringifyInner(value, state);
 }
 function createHashFragment(input, length) {
     return sha256Hex(input).substring(0, length);
@@ -74,7 +172,16 @@ function buildCacheKey(namespace, urlHash, varyHash) {
 function getVaryHash(vary) {
     if (!vary)
         return undefined;
-    const varyString = typeof vary === 'string' ? vary : stableStringify(vary);
+    let varyString;
+    if (typeof vary === 'string') {
+        varyString =
+            vary.length > CACHE_VARY_LIMITS.MAX_STRING_LENGTH ? null : vary;
+    }
+    else {
+        varyString = stableStringify(vary);
+    }
+    if (varyString === null)
+        return null;
     if (!varyString)
         return undefined;
     return createHashFragment(varyString, CACHE_HASH.VARY_HASH_LENGTH);
@@ -84,6 +191,8 @@ export function createCacheKey(namespace, url, vary) {
         return null;
     const urlHash = createHashFragment(url, CACHE_HASH.URL_HASH_LENGTH);
     const varyHash = getVaryHash(vary);
+    if (varyHash === null)
+        return null;
     return buildCacheKey(namespace, urlHash, varyHash);
 }
 export function parseCacheKey(cacheKey) {

package/dist/config.d.ts

@@ -1,4 +1,5 @@
 export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+export type TransformMetadataFormat = 'markdown' | 'frontmatter';
 interface AuthConfig {
     mode: 'oauth' | 'static';
     issuerUrl: URL | undefined;
@@ -40,6 +41,10 @@ export declare const config: {
         userAgent: string;
         maxContentLength: number;
     };
+    transform: {
+        timeoutMs: number;
+        metadataFormat: TransformMetadataFormat;
+    };
     cache: {
         enabled: boolean;
         ttl: number;
@@ -59,7 +64,7 @@ export declare const config: {
     };
     security: {
         blockedHosts: Set<string>;
-        blockedIpPatterns: RegExp[];
+        blockedIpPatterns: readonly [RegExp, RegExp, RegExp, RegExp, RegExp, RegExp, RegExp, RegExp, RegExp, RegExp, RegExp, RegExp, RegExp, RegExp, RegExp];
         allowedHosts: Set<string>;
         apiKey: string | undefined;
         allowRemote: boolean;

package/dist/config.js

@@ -104,12 +104,19 @@ function parseLogLevel(envValue) {
         return 'info';
     return isLogLevel(level) ? level : 'info';
 }
+function parseTransformMetadataFormat(envValue) {
+    const normalized = envValue?.trim().toLowerCase();
+    if (normalized === 'frontmatter')
+        return 'frontmatter';
+    return 'markdown';
+}
 const SIZE_LIMITS = {
     TEN_MB: 10 * 1024 * 1024,
 };
 const TIMEOUT = {
     DEFAULT_FETCH_TIMEOUT_MS: 15000,
     DEFAULT_SESSION_TTL_MS: 30 * 60 * 1000,
+    DEFAULT_TRANSFORM_TIMEOUT_MS: parseInteger(process.env.TRANSFORM_TIMEOUT_MS, 30000, 5000, 120000),
 };
 function readCoreOAuthUrls() {
     return {
@@ -168,7 +175,9 @@ const ANY_V4 = buildIpv4([0, 0, 0, 0]);
 const METADATA_V4_AWS = buildIpv4([169, 254, 169, 254]);
 const METADATA_V4_AZURE = buildIpv4([100, 100, 100, 200]);
 const host = process.env.HOST ?? LOOPBACK_V4;
-const port = parseInteger(process.env.PORT, 3000, 1024, 65535);
+const port = process.env.PORT?.trim() === '0'
+    ? 0
+    : parseInteger(process.env.PORT, 3000, 1024, 65535);
 const baseUrl = new URL(`http://${formatHostForUrl(host)}:${port}`);
 const allowRemote = parseBoolean(process.env.ALLOW_REMOTE, false);
 const runtimeState = {
@@ -197,6 +206,10 @@ export const config = {
         userAgent: process.env.USER_AGENT ?? 'superFetch-MCP/2.0',
         maxContentLength: SIZE_LIMITS.TEN_MB,
     },
+    transform: {
+        timeoutMs: TIMEOUT.DEFAULT_TRANSFORM_TIMEOUT_MS,
+        metadataFormat: parseTransformMetadataFormat(process.env.TRANSFORM_METADATA_FORMAT),
+    },
     cache: {
         enabled: parseBoolean(process.env.CACHE_ENABLED, true),
         ttl: parseInteger(process.env.CACHE_TTL, 3600, 60, 86400),

package/dist/fetch.js

@@ -8,9 +8,7 @@ import { Agent } from 'undici';
 import { config } from './config.js';
 import { createErrorWithCode, FetchError, isSystemError } from './errors.js';
 import { getOperationId, getRequestId, logDebug, logError, logWarn, redactUrl, } from './observability.js';
-function isRecord(value) {
-    return typeof value === 'object' && value !== null;
-}
+import { isRecord } from './utils.js';
 function buildIpv4(parts) {
     return parts.join('.');
 }
@@ -368,23 +366,32 @@ function selectLookupResult(list, useAll, hostname) {
 function findLookupError(list, hostname) {
     return (findInvalidFamilyError(list, hostname) ?? findBlockedIpError(list, hostname));
 }
+function normalizeAndValidateLookupResults(addresses, resolvedFamily, hostname) {
+    const list = normalizeLookupResults(addresses, resolvedFamily);
+    const error = findLookupError(list, hostname);
+    return { list, error };
+}
+function respondLookupError(callback, error, addresses) {
+    callback(error, addresses);
+}
+function respondLookupSelection(callback, selection) {
+    if (selection.error) {
+        callback(selection.error, selection.fallback);
+        return;
+    }
+    callback(null, selection.address, selection.family);
+}
 function handleLookupResult(error, addresses, hostname, resolvedFamily, useAll, callback) {
     if (error) {
-        callback(error, addresses);
+        respondLookupError(callback, error, addresses);
         return;
     }
-    const list = normalizeLookupResults(addresses, resolvedFamily);
-    const lookupError = findLookupError(list, hostname);
+    const { list, error: lookupError } = normalizeAndValidateLookupResults(addresses, resolvedFamily, hostname);
     if (lookupError) {
-        callback(lookupError, list);
-        return;
-    }
-    const selection = selectLookupResult(list, useAll, hostname);
-    if (selection.error) {
-        callback(selection.error, selection.fallback);
+        respondLookupError(callback, lookupError, list);
         return;
     }
-    callback(null, selection.address, selection.family);
+    respondLookupSelection(callback, selectLookupResult(list, useAll, hostname));
 }
 function resolveDns(hostname, options, callback) {
     const { normalizedOptions, useAll, resolvedFamily } = buildLookupContext(options);
@@ -556,11 +563,64 @@ function publishFetchEvent(event) {
         // Avoid crashing the publisher if a subscriber throws.
     }
 }
-export function startFetchTelemetry(url, method) {
+function buildContextFields(context) {
+    const fields = {};
+    if (context.contextRequestId) {
+        fields.contextRequestId = context.contextRequestId;
+    }
+    if (context.operationId) {
+        fields.operationId = context.operationId;
+    }
+    return fields;
+}
+function buildResponseMetadata(response, contentSize) {
+    const contentType = response.headers.get('content-type') ?? undefined;
+    const contentLengthHeader = response.headers.get('content-length');
+    const size = contentLengthHeader ??
+        (contentSize === undefined ? undefined : String(contentSize));
+    const metadata = {};
+    if (contentType)
+        metadata.contentType = contentType;
+    if (size)
+        metadata.size = size;
+    return metadata;
+}
+function logSlowRequest(context, duration, durationLabel, contextFields) {
+    if (duration <= 5000)
+        return;
+    logWarn('Slow HTTP request detected', {
+        requestId: context.requestId,
+        url: context.url,
+        duration: durationLabel,
+        ...contextFields,
+    });
+}
+function resolveSystemErrorCode(error) {
+    return isSystemError(error) ? error.code : undefined;
+}
+function buildFetchErrorEvent(context, err, duration, contextFields, status, code) {
+    const event = {
+        v: 1,
+        type: 'error',
+        requestId: context.requestId,
+        url: context.url,
+        error: err.message,
+        duration,
+        ...contextFields,
+    };
+    if (code !== undefined) {
+        event.code = code;
+    }
+    if (status !== undefined) {
+        event.status = status;
+    }
+    return event;
+}
+function createTelemetryContext(url, method) {
     const safeUrl = redactUrl(url);
     const contextRequestId = getRequestId();
     const operationId = getOperationId();
-    const context = {
+    return {
         requestId: randomUUID(),
         startTime: performance.now(),
         url: safeUrl,
@@ -568,92 +628,55 @@ export function startFetchTelemetry(url, method) {
         ...(contextRequestId ? { contextRequestId } : {}),
         ...(operationId ? { operationId } : {}),
     };
+}
+export function startFetchTelemetry(url, method) {
+    const context = createTelemetryContext(url, method);
+    const contextFields = buildContextFields(context);
     publishFetchEvent({
         v: 1,
         type: 'start',
         requestId: context.requestId,
         method: context.method,
         url: context.url,
-        ...(context.contextRequestId
-            ? { contextRequestId: context.contextRequestId }
-            : {}),
-        ...(context.operationId ? { operationId: context.operationId } : {}),
+        ...contextFields,
     });
     logDebug('HTTP Request', {
         requestId: context.requestId,
         method: context.method,
         url: context.url,
-        ...(context.contextRequestId
-            ? { contextRequestId: context.contextRequestId }
-            : {}),
-        ...(context.operationId ? { operationId: context.operationId } : {}),
+        ...contextFields,
     });
     return context;
 }
 export function recordFetchResponse(context, response, contentSize) {
     const duration = performance.now() - context.startTime;
     const durationLabel = `${Math.round(duration)}ms`;
+    const contextFields = buildContextFields(context);
+    const responseMetadata = buildResponseMetadata(response, contentSize);
     publishFetchEvent({
         v: 1,
         type: 'end',
         requestId: context.requestId,
         status: response.status,
         duration,
-        ...(context.contextRequestId
-            ? { contextRequestId: context.contextRequestId }
-            : {}),
-        ...(context.operationId ? { operationId: context.operationId } : {}),
+        ...contextFields,
     });
-    const contentType = response.headers.get('content-type');
-    const contentLength = response.headers.get('content-length') ??
-        (contentSize === undefined ? undefined : String(contentSize));
     logDebug('HTTP Response', {
         requestId: context.requestId,
         status: response.status,
         url: context.url,
         duration: durationLabel,
-        ...(context.contextRequestId
-            ? { contextRequestId: context.contextRequestId }
-            : {}),
-        ...(context.operationId ? { operationId: context.operationId } : {}),
-        ...(contentType ? { contentType } : {}),
-        ...(contentLength ? { size: contentLength } : {}),
+        ...contextFields,
+        ...responseMetadata,
     });
-    if (duration > 5000) {
-        logWarn('Slow HTTP request detected', {
-            requestId: context.requestId,
-            url: context.url,
-            duration: durationLabel,
-            ...(context.contextRequestId
-                ? { contextRequestId: context.contextRequestId }
-                : {}),
-            ...(context.operationId ? { operationId: context.operationId } : {}),
-        });
-    }
+    logSlowRequest(context, duration, durationLabel, contextFields);
 }
 export function recordFetchError(context, error, status) {
     const duration = performance.now() - context.startTime;
     const err = error instanceof Error ? error : new Error(String(error));
-    const event = {
-        v: 1,
-        type: 'error',
-        requestId: context.requestId,
-        url: context.url,
-        error: err.message,
-        duration,
-        ...(context.contextRequestId
-            ? { contextRequestId: context.contextRequestId }
-            : {}),
-        ...(context.operationId ? { operationId: context.operationId } : {}),
-    };
-    const code = isSystemError(err) ? err.code : undefined;
-    if (code !== undefined) {
-        event.code = code;
-    }
-    if (status !== undefined) {
-        event.status = status;
-    }
-    publishFetchEvent(event);
+    const contextFields = buildContextFields(context);
+    const code = resolveSystemErrorCode(err);
+    publishFetchEvent(buildFetchErrorEvent(context, err, duration, contextFields, status, code));
     const log = status === 429 ? logWarn : logError;
     log('HTTP Request Error', {
         requestId: context.requestId,
@@ -661,10 +684,7 @@ export function recordFetchError(context, error, status) {
         status,
         code,
         error: err.message,
-        ...(context.contextRequestId
-            ? { contextRequestId: context.contextRequestId }
-            : {}),
-        ...(context.operationId ? { operationId: context.operationId } : {}),
+        ...contextFields,
     });
 }
 const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);

package/dist/http.d.ts

@@ -15,8 +15,14 @@ interface McpRequestBody {
     id?: string | number;
     params?: McpRequestParams;
 }
-export declare function startHttpServer(): Promise<{
+export declare function startHttpServer(options?: {
+    registerSignalHandlers?: boolean;
+}): Promise<{
     shutdown: (signal: string) => Promise<void>;
+    stop: () => Promise<void>;
+    url: string;
+    host: string;
+    port: number;
 }>;
 export declare function errorHandler(err: Error, req: Request, res: Response, next: NextFunction): void;
 export declare function normalizeHost(value: string): string | null;
@@ -55,6 +61,8 @@ export declare function ensureSessionCapacity({ store, maxSessions, res, evictOl
     res: Response;
     evictOldest: (store: SessionStore) => boolean;
 }): boolean;
+type CloseHandler = (() => void) | undefined;
+export declare function composeCloseHandlers(first: CloseHandler, second: CloseHandler): CloseHandler;
 export declare function resolveTransportForPost({ res, body, sessionId, options, }: {
     res: Response;
     body: Pick<McpRequestBody, 'method' | 'id'>;